///////////////////////////////////////////////////////////////////////////
//
// Copyright (c) 2000-2003 Intel Corporation 
// All rights reserved. 
//
// Redistribution and use in source and binary forms, with or without 
// modification, are permitted provided that the following conditions are met: 
//
// * Redistributions of source code must retain the above copyright notice, 
// this list of conditions and the following disclaimer. 
// * Redistributions in binary form must reproduce the above copyright notice, 
// this list of conditions and the following disclaimer in the documentation 
// and/or other materials provided with the distribution. 
// * Neither name of Intel Corporation nor the names of its contributors 
// may be used to endorse or promote products derived from this software 
// without specific prior written permission.
// 
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR 
// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY 
// OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
///////////////////////////////////////////////////////////////////////////


// ----------------------------------------------------------------------------
// CHANGES:
//
// author: Daniel Lerch <dlerch@gmail.com>, http://opendomo.com
// date: January 2007
// ----------------------------------------------------------------------------



#ifndef __UTIL_H__
#define __UTIL_H__

#ifdef __cplusplus
extern "C" {
#endif

#include <stdlib.h>

#include <string.h>

#include <upnp/upnptools.h>
#include <upnp/ithread.h>
#include <upnp/ixml.h>

//mutex to control displaying of events
extern ithread_mutex_t display_mutex ;

typedef enum 
{
	STATE_UPDATE = 0,
	DEVICE_ADDED =1,
	DEVICE_REMOVED=2,
	GET_VAR_COMPLETE=3
} eventType;


/**
 * Given a DOM node such as <Channel>11</Channel>, this routine
 * extracts the value (e.g., 11) from the node and returns it as 
 * a string. The string must be freed by the caller using 
 * free.
 *
 * @param element: The DOM node from which to extract the value
 */
char *util_get_element_value(IN IXML_Element *element);


/**
 * Given a DOM node representing a UPnP Device Description Document,
 * this routine parses the document and finds the first service list
 * (i.e., the service list for the root device).  The service list
 * is returned as a DOM node list. The NodeList must be freed using
 * NodeList_free.
 *
 * @param doc: The DOM node from which to extract the service list
 */
IXML_NodeList *util_get_first_service_list(IN IXML_Document * doc); 


/**
 * Given a document node, this routine searches for the first element
 * named by the input string item, and returns its value as a string.
 * String must be freed by caller using free.
 * 
 * @param doc: The DOM document from which to extract the value
 * @param item: The item to search for
 *
 */
char *util_get_first_document_item(IN IXML_Document *doc, IN const char *item);


/**
 * Given a DOM element, this routine searches for the first element
 * named by the input string item, and returns its value as a string.
 * The string must be freed using free.
 * 
 * @param node: The DOM element from which to extract the value
 * @param item: The item to search for
 */
char *util_get_first_element_item(IN IXML_Element *element,IN const char *item);


/**
 * Prints a callback event type as a string.
 *
 * @param S: The callback event
 */
void util_print_event_type(IN Upnp_EventType S);


/**
 * Prints callback event structure details.
 *
 * @param EventType: The type of callback event
 * @param Event: The callback event structure
 *
 */
int util_print_event(IN Upnp_EventType EventType, IN void *Event);


/**
 * This routine finds the first occurance of a service in a DOM representation
 * of a description document and parses it.  Note that this function currently
 * assumes that the eventURL and controlURL values in the service definitions
 * are full URLs.  Relative URLs are not handled here.
 *
 * @param DescDoc: The DOM description document
 * @param location: The location of the description document
 * @param serviceSearchType: The type of service to search for
 * @param serviceId: (out) The service ID
 * @param eventURL: (out) The event URL for the service
 * @param controlURL: (out) The control URL for the service
 */
int util_find_and_parse_service (IN IXML_Document *DescDoc, IN char* location, 
				    IN char *serviceType, OUT char **serviceId, 
				    OUT char **eventURL, OUT char **controlURL);


/**
 * Prototype for displaying strings. All printing done by the device,
 * control point, and sample util, ultimately use this to display strings 
 * to the user.
 *
 * @param string: string to print
 *
 */
typedef void (*print_string)(const char *string);


//global print function used by sample util
extern print_string gPrintFun;


/**
 * Prototype for passing back state changes
 *
 * @param  const char * varName
 * @param  const char * varValue
 * @param  const char * UDN
 * @param  int          newDevice
 */
typedef void (*state_update)( const char *varName, const char *varValue, 
                           const char *UDN, eventType type);

//global state update function used by smaple util
extern state_update gStateUpdateFun;

/**
 * Initializes the sample util. Must be called before any sample util 
 * functions. May be called multiple times.
 *
 *   print_function - print function to use in util_print
 */
int util_initialize(print_string print_function);

/**
 * Releases Resources held by sample util.
 */
int util_finish(void);

/**
 * Function emulating printf that ultimately calls the registered print 
 * function with the formatted string.
 *
 *  @param:  fmt - format (see printf)
 *   . . .  - variable number of args. (see printf)
 */
int util_print( char *fmt, ... );

/**
 *
 * @param update_function: 
 */
int util_register_update_function(state_update update_function);

/**
 *
 * @param varName: 
 * @param varValue: 
 * @param UDN: 
 * @param type: 
 */
void util_state_update( const char *varName, const char *varValue, 
                       const char *UDN, eventType type);

#ifdef __cplusplus
}
#endif

#endif

